gh-142044: Add note to prefer asyncio.timeout/timeout_at over Timeout #144449
Conversation
kovan
requested review from
1st1,
asvetlov,
kumaraditya303 and
willingc
as code owners
Doc/library/asyncio-task.rst
Outdated
| An :ref:`asynchronous context manager <async-context-managers>` | ||
| for cancelling overdue coroutines. | ||
|
|
||
| .. note:: |
There was a problem hiding this comment.
This note should be placed elsewhere. Either after the class definition or before introducing it.
|
A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated. Once you have made the requested changes, please leave a comment on this pull request containing the phrase |
…imeout Document that users should prefer using asyncio.timeout() or asyncio.timeout_at() rather than directly instantiating the Timeout class, matching the guidance already present in the source code. Co-Authored-By: Claude Opus 4.5 <[email protected]>
kovan
force-pushed
the
gh-142044-asyncio-timeout-docs
branch
from
893bb26 to
73df00f
Compare
|
I have made the requested changes; please review again |
|
Thanks for making the requested changes! @picnixz: please review the changes made to this pull request. |
| The context manager produced by :func:`asyncio.timeout` can be | ||
| rescheduled to a different deadline and inspected. | ||
|
|
||
| .. note:: |
There was a problem hiding this comment.
After looking at the generated doc, I think a note is a bit too loud. OTOH, I feel that having Timeout inside the docs of timeout is also wrong. My suggestion is to put it as a real documented class (outside the function description) and put that note there.
@kumaraditya303 How do you want the docs to be eventually rendered?
There was a problem hiding this comment.
How do you want the docs to be eventually rendered?
I don't want to highlight timeout class much more than what it is already so let's keep it inside. I agree that note is bit louder so maybe we can just add it in the description.
There was a problem hiding this comment.
Ok, so let's just make it part of the class description, without a note.
3 participants
Summary
Timeoutclass documentation recommending that users preferasyncio.timeout()orasyncio.timeout_at()rather than instantiatingTimeoutdirectlyLib/asyncio/timeouts.py:26-28Test plan
make checkpassed in Doc/ directory🤖 Generated with Claude Code
asyncio.timeout[at]should be preferred overasyncio.Timeout#142044📚 Documentation preview 📚: https://cpython-previews--144449.org.readthedocs.build/